MathPad XFuns allow externally compiled functions to be added to the Functions menu.
The XFun kit contains interface routines and C source code for several example XFuns. CodeWarrior 8 projects are included but Think C or other development systems should be able to create Xfuns as well. The "util" folder contains general interface routines and headers.
MathPad 68K XFuns use SANE 80-bit floating point numbers. The example projects are set so that the type "double" is 80-bit.
XFun files are of type 'XFun' and creator 'MPad'. The resource fork contains one or more code resources of type 'XFun'. (Native PowerPC XFuns use the Code Fragment Manager rather that code resources. See "PPC Notes" for details.)
When MathPad is launched it checks for XFun files in the same folder as the application. Any 'XFun' code resources are loaded in.
Any named 'TEXT' resources in XFun files are added to MathPad's Help menu. The resource name is used as the menu item. When the menu item is selected, a window with the help text will be opened. This allows XFun files to provide help info about the functions they define.
----- See the file "mod.c" for an example of a simple XFun. --------
MathPad does a call to the beginning of the code resource on application startup. The resource header then calls main(). The parameter to main() is a callback function pointer. The main() routine is used to perform any initialization needed. Usually all it does is use the callback
to install the function in MathPad. The "name" string gives the name that MathPad will use for the new function. The "parms" string gives a formal parameter list. This parameter list appears in the menu and is used to check for the correct number of parameters. The "entry" pointer points to the code for the new function. MathPad will call the function at "entry" each time it needs to evaluate the external function. The "predef" pointer points to a function that will be called each time the document is reevaluated. If you do not need this hook, pass NULL.
When an external function is evaluated by Mathpad, the code resource's installed function is called with two parameters, a pointer to an 80-bit double for the numeric result and the callback entry point. The function should store its result and return TRUE. If the result can not be calculated it should return FALSE. (The function may also return FALSE if it passes back its results in a globals rather than the result parameter). Access to the MathPad actual parameters is via callback routines.
See the file callback.h for descriptions of the available MathPad callback routines. The file callback.c provides individual interface routines from the single callback entry point.
External functions that calculate a single result based on a few numeric parameters are quite simple and probably only require the callback
GetParmVal(int n,double *num,funptr callback)
which gets the numeric value of parameter n. MathPad numbers its parameters in a slightly obtuse manner. Parameters are numbered from right to left starting with 0.
--- See the files "cross.c" and "histogram.c" for examples using arrays ---
Operating on arrays introduces more complication. MathPad arrays can have any number of dimensions and can be any size. Callback routines are provided to access and manipulate MathPad's general expression structure.
The callback
MakeParmExpr(long n,EXPR *xpr,funptr callback)
makes an expression structure for parameter n. Details of this structure are not needed since there is no need to access it directly. The expression structure allocated by MakeParmExpr() must be deallocted by FreeExpr() before returning.
Accessing 1D or 2D arrays is easiest. The callback
allocates space for the matrix, evaluates all of its elements and passes back a pointer to the allocated block. An array with more than 2 dimensions will generate an error message and return false. The matrix allocated by GetExprMatrix() should be deallocated with DisposPtr().
For arrays of more than 2 dimensions or cases where it is better to evaluate individual elements, use the callbacks
The array must be allocated via NewPtr() and will be deallocated by MathPad. For more than 2 dimensions the callback
FoldVar(char *name,long lim,funptr callback)
can be called any number of times to add dimensions to the array made by SetVarMatrix().
A single value can be assigned to a global with the callback
SetVarVal(char *name,double num,funptr callback)
There are also callbacks to get values from global variables.
GetVarVal(char *name,double *num,funptr callback)
MakeVarExpr(char *name,EXPR *xpr,funptr callback)
XFuns can be set up to return fixed size arrays directly. A predef routine must be used. The callback
AddFunDim(char *name,long lim,funptr callback)
can be called from the predef routine to tell MathPad that the named XFun will process index values. AddFunDim() can be called multiple times to setup a multidimensional function. When the XFun is called, each dimension appends an index value to the actual parameter list. The index values are accessed via GetParmVal(). An "array" function must compute its return value based on the index. MathPad only evaluates the elements that it needs and there are no guarantees as to which elements will be evaluated or what order they are evaluated in.
For simple functions the XFun does not need to keep any data between calls. More complex routines will likely need to use global variables. If you use ANY global variables you will have to deal with setting up A4. By default CodeWarrior allocates strings off A4 so unless you choose PC-relative strings, you will need A4 globals just to use string constants.
68K Mac applications access global data relative to the A5 register. Code resources are compiled separately from the application. They can't blindly store data relative to A5 since it would overwrite the application's variables. The usual solution to this is to have the code resource allocate its own global area and access it off of the A4 register. When making a code resource, the compiler generates code to use A4 rather than A5. The programmer must make sure that A4 gets set up properly whenever code from the resource is executing.
The files "A4globs.h" and "entry.c" provide a generic way to handle setting and restoring A4. These A4 files have been tried with Think C 5 and CodeWarrior 8. For other compilers you are on your own. Read the compiler manual carefully about the details of how to compile code resources. Any libraries used must be compiled for A4 globals.
A "uses globals" version of the callbacks is provided via files "callbackg.h" and "callbackg.c". If the XFun needs to use globals anyway, it is more convienient to save the callback pointer in a global rather than pass it as a parameter every time.
--------- Error handling --------------
Execution of the XFun is not interruptable. If the calculation can take a long time, the callback
SpinWatch()
should be used to allow computation to be switched to background or stopped via command period. If command period was hit, SpinWatch() will set the stop flag. The state of this flag can be checked with the callback
Stopped()
The stop flag may also be set if there is a severe error when evaluating a MathPad expression. Stopped() should be checked if EvalExpr() is called in a loop. Once the stop flag is set, any attempt to evaluate a MathPad expression will immediately return false.
The callback
ErrMsg(char *fmt,char *str)
gives an error message for the status line. Calling ErrMsg() sets the stop flag and will cause MathPad to stop evaluation when the Xfun returns. The fmt and str get passed to sprintf(). If fmt is a simple message with no parameters, pass NULL for str. You can cheat somewhat on the value for str. You can print an integer value with ErrMsg("%ld",(char *)n).
-------- memory allocation ---------------------
Usually any memory allocated by the XFun should be deallocated before returning. This applies to error returns as well as the normal return.
• Expression structures allocated by MakeParmExpr() or MakeVarExpr() must be deallocated by FreeExpr().
• MathPad allocates memory for the matrix returned by GetExprMatrix(). The Xfun must deallocate it with the toolbox call DisposPtr().
• Arrays allocated and passed to SetVarMatrix() will be deallocated by MathPad and should NOT be deallocated by the XFun.
-------- multiple functions in one file ----------
More than one XFun can be defined in a single Xfun file. Multiple functions can be installed from a single resource by calling AddXfun() for each function. It is also allowable to put more than one 'XFun' resource into a single Xfun file. Resource IDs do not matter (as long as they are unique).
The XFun resource file is only open during MathPad startup. This means that XFuns can not expect access to private resources simply by adding them to the XFun file. Any resources in the XFun file are available during the call to main() but not during the call to the function itself. The main() routine can load resources and detach them.
-- Send comments, questions, suggestions and bug reports to:
